ПРОЦЕДУРА ЗАВАНТАЖЕННЯ БАЗОВОЇ СИСТЕМИ¶

Цей процес змінювався із розвитком бібліотеки і продовжує змінюватися. Наведений тут опис відповідає поточній версії libguestfs. Його надано із інформаційною метою.

Для виконання описаних нижче кроків увімкніть діагностику у libguestfs (встановіть значення змінної середовища "LIBGUESTFS_DEBUG=1").

Створення базової системи

"supermin --build" викликається для створення ядра, невеличкого initrd та базової системи.

Кеш базової системи зберігається у /var/tmp/.guestfs-<UID> (або іншому каталозі, якщо встановлено значення змінної середовища "LIBGUESTFS_CACHEDIR" або "TMPDIR").

Щоб ознайомитися із повним описом створення базової системи та особливостями кешування, прочитайте сторінку підручника щодо supermin(1).

Запуск qemu і завантаження ядра

qemu викликається для завантаження ядра.

Запуск initrd

"supermin --build" збирає невеличкий initrd. initrd не є базовою системою. Метою роботи initrd є завантаження достатньої кількості модулів ядра для того, щоб можна було змонтувати і запустити саму базову систему.

initrd є архівом cpio із назвою /var/tmp/.guestfs-<UID>/appliance.d/initrd.

Після запуску initrd ви побачите повідомлення щодо завантаження модулів ядра, подібні до таких:

 supermin: ext2 mini initrd starting up
 supermin: mounting /sys
 supermin: internal insmod libcrc32c.ko
 supermin: internal insmod crc32c-intel.ko
    

Пошук і монтування пристрою базової системи

Базовою системою є розріджений файл, що містить файлову систему ext2 зі звичайною (але зменшеною у розмірах) операційною системою Linux. За звичайних умов, цей файл називається /var/tmp/.guestfs-<UID>/appliance.d/root.

Звичайні диски, які досліджуються за допомогою libguestfs, є першими пристроями, які «бачить» qemu (eg. as /dev/vda).

Останнім диском, який додано до qemu, є сама базова система (наприклад, /dev/vdb, якщо був лише один звичайний диск).

Таким чином, останнім завданням initrd є визначення розташування диска базової системи, його монтування та перемикання кореневої файлової системи на базову систему і запуск /init з базової системи.

Якщо усе працюватиме як слід, ви побачите такі повідомлення:

 supermin: picked /sys/block/vdb/dev as root device
 supermin: creating /dev/root as block special 252:16
 supermin: mounting new root on /root
 supermin: chroot
 Starting /init script ...
    

Зауважте, що повідомлення "Starting /init script ..." означає, що запущено скрипт ініціалізації (init) базової системи.

Ініціалізація базової системи

Далі, базова система ініціалізується. Ця процедура включає запуск певних процесів, зокрема "udev", можливе виведення певної діагностичної інформації і, нарешті, запуск фонової служби ("guestfsd").

Фонова служба

На останньому етапі фонова служба ("guestfsd") працює у базовій системі. Якщо запуск служби виконано вдало, ви побачите таке повідомлення:

 verbose daemon enabled
    

Фонова служба очікує виявити іменований послідовний порт virtio, відкритий qemu і з'єднаний іншим боком із бібліотекою.

Фонова служба встановлює з'єднання з цим портом (а отже і з бібліотекою) і надсилає чотирибайтове повідомлення "GUESTFS_LAUNCH_FLAG", яке ініціює протокол обміну даними (див. нижче).

ПРОТОКОЛ ОБМІНУ ДАНИМИ¶

Не покладайтеся на викладені у цьому розділі подробиці протоколу безпосередньо. Документація цього розділу стосується поточних принципів його роботи, але вони можуть змінитися у майбутніх версіях.

Протокол, який використовується для обміну даними між бібліотекою та фоновою службою, запущеною всередині віртуальної машини qemu, простим механізмом RPC, побудованим на основі XDR (RFC 1014, RFC 1832, RFC 4506).

Докладний формат структур описано у файлі common/protocol/guestfs_protocol.x (зауваження: цей файл створюється автоматично під час збирання бібліотеки).

Існує два широких класи: звичайні функції, які не мають параметрів "FileIn" і "FileOut" і які керуються дуже простим повідомленнями запитів і відповідей, і функції, які мають параметри "FileIn" або "FileOut" і які використовують такі самі повідомлення запитів і відповідей, але за повідомленням може слідувати файл, який надсилається у певному фрагментному кодуванні.

ЗВИЧАЙНІ ФУНКЦІЇ (БЕЗ ПАРАМЕТРІВ FILEIN/FILEOUT)

Повідомлення запиту для звичайних функцій:

 загальна довжина (заголовок + аргументи,
      але без включення самого слова length)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_args (у кодуванні XDR)

Поле загальної довжини надає змогу фоновій службі отримувати фіксований буфер у пам'яті, до якого вона записуватиме решту повідомлення. Отже, загальну довжину обмежено до "GUESTFS_MESSAGE_MAX" байтів (у поточній версії, 4 МБ), що означає, що ефективний розмір будь-якого запису обмежено цим обсягом пам'яті.

Зауважте, що багато функцій не приймають жодних аргументів. Для таких функцій "guestfs_щось_args" взагалі не вказують.

У заголовку міститься номер процедури ("guestfs_proc"), за допомогою якого функція-отримувач визначає тип структури аргументів, який слід очікувати, або дізнається про те, що аргументів не буде.

Для функцій, які приймають необов'язкові аргументи, додаткові аргументи кодуються у структуру "guestfs_foo_args" у той самий спосіб, що і звичайні аргументи. Бітова маска у заголовку позначає, які додаткові аргументи мають значення. Виконується також перевірка бітової маски на вміст бітів, про які не знає фонова служба (наприклад, якщо у новішій версії бібліотеки додано додаткові аргументи). Виклики із такими бітами відкидаються.

Повідомлення відповіді для звичайних функцій:

 загальна довжина (заголовок + повернуте значення,
      але без включення самого слова length)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_ret (у кодуванні XDR)

Як і вище, структуру "guestfs_щось_ret" може бути повністю пропущено, якщо функція формально не повертає значень.

Як і вище, значення загальної довжини відповіді обмежується значенням "GUESTFS_MESSAGE_MAX".

Якщо станеться помилка, у заголовку буде встановлено прапорець, а саме повідомлення відповіді буде дещо змінено:

 загальна довжина (заголовок + помилка,
      але без включення самого слова length)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_message_error (у кодуванні XDR)

Структура "guestfs_message_error" містить повідомлення про помилку у форматі рядка.

ФУНКЦІЇ З ПАРАМЕТРАМИ FILEIN

Параметр "FileIn" позначає, що ми передаємо файл до гостьової системи. Надсилається звичайне повідомлення запиту (див. вище). Втім, за ним слідує послідовність фрагментів файла.

 загальна довжина (заголовок + аргументи,
      але без включення самого слова length,
      і без включення фрагментів)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_args (у кодуванні XDR)
 послідовність фрагментів для параметра 0 FileIn
 послідовність фрагментів для параметра 1 FileIn тощо
«Послідовність фрагментів» це:
 довжина фрагмента (без самого слова length)
 struct guestfs_chunk (у кодуванні XDR)
довжина фрагмента
 struct guestfs_chunk (у кодуванні XDR)
   ...
довжина фрагмента
 struct guestfs_chunk (із data.data_len == 0)

Значення "data_len" останнього фрагмента дорівнює нулю. Крім того, у останньому фрагментів встановлено прапорець, який позначає успішне завершення або передчасне переривання.

На момент написання цього підручника не існувало жодної функції, яка б приймала більше одного параметра FileIn. Втім, теоретично, підтримку багатьох таких параметрів передбачено. Адже передбачено можливість надсилати послідовність фрагментів для кожного параметра FileIn один фрагмент за одним (зліва праворуч).

Передавання даних може бути скасовано як бібліотекою (відправником), так і фоновою службою (отримувачем). Бібліотека скасовує передавання надсиланням фрагмента із спеціальним прапорцем, який позначає скасовування. Коли фонова служба отримує такий фрагмент, вона скасовує увесь RPC, не надсилає жодної відповіді і повертається до читання наступного запиту.

Фонова служба також може скасувати передавання даних. Зробити це вона можна записуванням до сокета спеціального слова "GUESTFS_CANCEL_FLAG". Бібліотека очікує на цьому сокеті на дані під час передавання. Якщо буде отримано спеціальне слово, бібліотека скасує передавання (надішле фрагмент скасовування). Спеціальне слово вибрано так, щоб навіть якщо скасовування станеться безпосередньо наприкінці передавання (після того, як бібліотека завершить запис і розпочне очікувати на відповідь), «неоднозначний» прапорець скасовування не буде переплутано із повідомленням відповіді.

Цей протокол уможливлює передавання файлів довільного розміру (без обмеження у 32 біти), а також файлів, розмір яких невідомий наперед (наприклад з каналів обробки даних або сокетів). Втім, фрагменти є доволі малими ("GUESTFS_MAX_CHUNK_SIZE"), отже, ні бібліотеці, ні фоновій службі не потрібно для передавання багато оперативної пам'яті.

FФУНКЦІЇ З ПАРАМЕТРАМИ FILEOUT

Протокол для параметрів FileOut є тим самим, що і для параметрів FileIn, але у ньому фонова служба і бібліотека міняються місцями.

 загальна довжина (заголовок + повернуте значення,
      але без включення самого слова length,
      і без включення фрагментів)
 struct guestfs_message_header (у кодуванні XDR)
 struct guestfs_<щось>_ret (у кодуванні XDR)
 послідовність фрагментів для параметра 0 FileOut
 послідовність фрагментів для параметра 1 FileOut тощо
=head3 ПОЧАТКОВЕ ПОВІДОМЛЕННЯ

Під час запуску фонова служба надсилає початкове слово ("GUESTFS_LAUNCH_FLAG"), яке означає, що гостьова система і фонова служба працюють. Саме на це очікує "guestfs_launch" in guestfs(3).

ПОВІДОМЛЕННЯ ЩОДО ПОСТУПУ

Фонова служба може будь-коли надсилати сповіщення щодо поступу. Ці сповіщення відрізняються від інших тим, що звичайне слово length замінюється на "GUESTFS_PROGRESS_FLAG", а за ним слідує повідомлення щодо поступу фіксованого розміру.

Бібліотека перетворює їх на зворотні виклики щодо поступу (див. "GUESTFS_EVENT_PROGRESS" in guestfs(3)), якщо зареєстровано зворотний виклик; або відкидає їх, якщо виклик не зареєстровано.

Фонова служба автоматично обмежує частоту повідомлень щодо поступу, які вона надсилає (див. "daemon/proto.c:notify_progress"). Не усі виклики створюють повідомлення щодо поступу.

ФІКСОВАНА БАЗОВА СИСТЕМА¶

Під час роботи libguestfs (або інструментів libguestfs) виконується пошук базової системи у відповідному каталозі. Типовий шлях до цього каталогу вбудовано до libguestfs, його також можна змінити за допомогою змінної середовища "LIBGUESTFS_PATH".

Зазвичай, базова система supermin зберігається саме у цьому каталозі (див. "БАЗОВА СИСТЕМА SUPERMIN" in supermin(1)). libguestfs перебудовує її у повноцінну базову систему за допомогою команди "supermin --build".

Втім, також можна скористатися простішою «фіксованою базовою системою». libguestfs визначає таку систему, виконуючи пошук каталогу, який містить такі файли:

• kernel
• initrd
• root
• README.fixed (зауважте, що він також має бути)

Якщо буде виявлено фіксовану базову систему, libguestfs не використовуватиме supermin взагалі і запустить віртуальну машину (за допомогою qemu або поточного модуля обробки, див. "МОДУЛЬ" in guestfs(3)) із ядром, initrd та кореневим диском із фіксованої базової системи.

Отже, фіксованою базовою системою можна скористатися, якщо для платформи або дистрибутива Linux не передбачено підтримки supermin. Ви збираєте базову систему на платформі, де таку підтримку передбачено, за допомогою libguestfs-make-fixed-appliance(1), копіюєте її і використовуєте для запуску libguestfs.